# Xoron Arithmetic Library Description

This document outlines the arithmetic Xoron library. The purpose of this document is to give general guidelines on the arithmetic library, and how to use it.

## Definitions

The Xoron Arithmetic library header has the following definitions.

[comment]: <> (../inc/xrn_arithmetic.h)
```Xoronos_C
#ifndef XORON_ARITHMETIC_H
#define XORON_ARITHMETIC_H
```

The library includes are used to get system parameters, define internal numerical types, generate confidential random numbers.

[comment]: <> (../inc/xrn_arithmetic.h)
```Xoronos_C
#include <stdint.h>
#include <stdbool.h> 
#include <string.h> 
#include <stdlib.h> 
#include "xrn_settings.h"
#include "xrn_common.h"
```

## Structures

The boolean type is redefined as below.

[comment]: <> (../inc/xrn_arithmetic.h)
```Xoronos_C
#define XBIT_TYPE bool
```

Architecture definition for the host machine. 
By default the host is assumed to have a 64 bit architecture.

[comment]: <> (../inc/xrn_arithmetic.h)
```Xoronos_C

#if !defined( XRN_ARC )
#define XRN_ARC
#define XARC64BIT 1
#define XARC32BIT 0
#define XARC16BIT 0
#define XARC08BIT 0
#endif

#if   ( XNBITS >= 64 ) && ( XARC64BIT )
   #define XINT_TYPE uint64_t
   #define XBASE_NUM  64
   #define PARITY_BIT __builtin_parityll
#elif ( XNBITS >= 32 ) && ( XARC32BIT )
   #define XINT_TYPE uint32_t
   #define XBASE_NUM  32
   #define PARITY_BIT __builtin_parity
#elif ( XNBITS >= 16 ) && ( XARC16BIT )
   #define XINT_TYPE uint16_t
   #define XBASE_NUM  16
#elif ( XNBITS >= 8 ) && ( XARC08BIT )
   #define XINT_TYPE uint8_t
   #define XBASE_NUM  8
#endif

#define XNBITS_NUM     XNBITS / XBASE_NUM

#if !defined( XNBYTES )
#define XNBYTES (XNBITS / 8)
#endif

```

The general number or equation is defined in the following structure.

[comment]: <> (../inc/xrn_arithmetic.h)
```Xoronos_C
typedef struct xnum_t {
   XINT_TYPE  xnum [XNBITS_NUM];
} xnum_t;  
```

A matrix is defined as an array of equations.

[comment]: <> (../inc/xrn_arithmetic.h)
```Xoronos_C
typedef struct xmat_t {
   xnum_t  xmat [XNBITS];
} xmat_t;  
```

## Macros

### Get and set information in the xnum_t type

Those macros are used to put and get bits and bytes into xnum_t and xmat_t data structures.

[comment]: <> (../inc/xrn_arithmetic.h)
```Xoronos_C

#define BYTE_GET(X,I) \
   (uint8_t)(X.xnum[(I*8)/XBASE_NUM] >> ((I*8)%XBASE_NUM))

#define BIT_GET(X,I) \
   (X.xnum[I/XBASE_NUM] >> (I%XBASE_NUM)) & 1 

#define BIT_SET(X,I) \
    (X.xnum[I/XBASE_NUM] |= ((XINT_TYPE)1 << (I%XBASE_NUM))) 

#define BIT_SETVAL(X,I,VAL) \
    X.xnum[I/XBASE_NUM] &= ~((XINT_TYPE)1 << (I%XBASE_NUM)); \
    X.xnum[I/XBASE_NUM]  = ((XINT_TYPE)VAL << (I%XBASE_NUM)) | X.xnum[I/XBASE_NUM]

```

### Binary Operation

Macros are used to perform binary operations with xnum_t data structures.

[comment]: <> (../inc/xrn_arithmetic.h)
```Xoronos_C

#define X_INV2( src, dst ) \
for(int lu=0;lu<XNBITS_NUM;lu++)  dst.xnum[lu] = ~ src.xnum[lu];

#define X_AND2( src, dst ) \
for(int lu=0;lu<XNBITS_NUM;lu++)  dst.xnum[lu] &= src.xnum[lu];  

#define X_AND3( src0, src1, dst ) \
for(int lu=0;lu<XNBITS_NUM;lu++)  dst.xnum[lu] = src0.xnum[lu] & src1.xnum[lu];  

#define X_OR2( src, dst ) \
for(int lu=0;lu<XNBITS_NUM;lu++)  = src.xnum[lu] | dst.xnum[lu];  

#define X_OR3( src0, src1, dst ) \
for(int lu=0;lu<XNBITS_NUM;lu++)  dst.xnum[lu] = src0.xnum[lu] | src1.xnum[lu];  

#define X_XOR2(src,dst)\
for(int lu=0;lu<XNBITS_NUM;lu++)  dst.xnum[lu] = dst.xnum[lu] ^ src.xnum[lu];  

#define X_XOR3(src0,src1,dst)\
for(int lu=0;lu<XNBITS_NUM;lu++)  dst.xnum[lu] = src0.xnum[lu] ^ src1.xnum[lu];  

#define X_MAJ( src0, src1, src2, dst ) \
for(int lu=0;lu<XNBITS_NUM;lu++)  dst.xnum[lu] = (src0.xnum[lu] & src1.xnum[lu]) | (src0.xnum[lu] & src2.xnum[lu]) | (src1.xnum[lu] & src2.xnum[lu]);
```

The library is used to compute the parity bit of an xnum_t number.

[comment]: <> (../inc/xrn_arithmetic.h)
```Xoronos_C

#define X_PARITY(E1,RES) \
    RES = 0;    \
    for(int lu=0;lu<XNBITS_NUM;lu++)  RES = ( RES ^ PARITY_BIT(E1.xnum[lu]) );

```

Furthermore, the library defines the following macros are used to compare internal data structures.

[comment]: <> (../inc/xrn_arithmetic.h)
```Xoronos_C

#define XNUM_CMP(E1,E2,RES) \
    RES = 0;    \
    for(int lu=0;(lu<XNBITS_NUM)&&(!RES);lu++)  RES = E1.xnum[lu] != E2.xnum[lu];


#define XMAT_CMP(E1,E2,RES) \
    RES = 0;    \
    for(int lu=0;(lu<XNBITS)&&(!RES);lu++) \
    for(int ll=0;(ll<XNBITS_NUM)&&(!RES);ll++)  RES = E1.xmat[lu].xnum[ll] != E2.xmat[lu].xnum[ll];
```

## Functions

### xrn_add_nums

**Description:**

The **xrn_add_nums** function is used to sum two xnum_t numbers. Its return value is either '0' if there is not overflow, and 1 if there is an overflow.

**Function declaration:**

[comment]: <> (../inc/xrn_arithmetic.h)
```Xoronos_C
int xrn_add_nums ( 
    xnum_t a, 
    xnum_t b, 
    int carry, 
    xnum_t * c
);
```

**Arguments description:**

> **input:** a $\rightarrow$ The first number to be added. \
> **input:** b $\rightarrow$ The second number to add. \
> **input:** carry $\rightarrow$ The input carry bit, either 0 or 1. \
> **output:** c $\rightarrow$ The result of the addition. 

[comment]: <> ( docautocomplete xrn_add_nums )

### xrn_subtract_nums

**Description:**

The **xrn_subtract_nums** function is used to subtract two xnum_t numbers. Its return value is either '0' if there is not overflow, and 1 if there is an overflow.

**Function declaration:**

[comment]: <> (../inc/xrn_arithmetic.h)
```Xoronos_C
int xrn_subtract_nums ( 
    xnum_t a, 
    xnum_t b, 
    xnum_t * c
);
```

**Arguments description:**

> **input:** a $\rightarrow$ The first number to be subtracted. \
> **input:** b $\rightarrow$ The second number to subtract. \
> **output:** c $\rightarrow$ The result of the subtraction. 

[comment]: <> ( docautocomplete xrn_subtract_nums )

### xrn_compare_greater_equal_nums

**Description:**

The **xrn_compare_greater_equal_nums** is used to enstablish if the first argument is greater than the second argument. 

**Function declaration:**

[comment]: <> (../inc/xrn_arithmetic.h)
```Xoronos_C
void xrn_compare_greater_equal_nums ( 
    xnum_t a, 
    xnum_t b, 
    int * res
);
```

**Arguments description:**

> **input:** a $\rightarrow$ The first number to be compared. \
> **input:** b $\rightarrow$ The second number to compare. \
> **output:** res $\rightarrow$ The result of the comparison, 0 if a is greater than b, 1 otherwise. 

[comment]: <> ( docautocomplete xrn_compare_greater_equal_nums )

### xrn_initialize_num 

**Description:**

The **xrn_initialize_num** is used to initialize a xnum to zero.

**Function declaration:**

[comment]: <> (../inc/xrn_arithmetic.h)
```Xoronos_C
void xrn_initialize_num ( 
    xnum_t * dst 
);
```

**Arguments description:**

> **output:** dst $\rightarrow$ The output of the initialization.

[comment]: <> ( docautocomplete xrn_initialize_num )

### xrn_initialize_mat 

**Description:**

The **xrn_initialize_mat** is used to initialize a matrix to zero.

**Function declaration:**

[comment]: <> (../inc/xrn_arithmetic.h)
```Xoronos_C
void xrn_initialize_mat ( 
    xmat_t * dst 
);
```

**Arguments description:**

> **output:** dst $\rightarrow$ The output of the initialization.

[comment]: <> ( docautocomplete xrn_initialize_mat )

### xrn_initialize_rnd_num

**Description:**

The **xrn_initialize_rnd_num** is used to initialize the content of the inputs pointer at random. The randomization is not a confidential one.

**Function declaration:**

[comment]: <> (../inc/xrn_arithmetic.h)
```Xoronos_C
void xrn_initialize_rnd_num ( 
    xnum_t * dst 
);
```

**Arguments description:**

> **output:** dst $\rightarrow$ The output of the initialization.

[comment]: <> ( docautocomplete xrn_initialize_rnd_num )

### xrn_initialize_rnd_mat

**Description:**

The **xrn_initialize_rnd_mat** is used to initialize the content of the inputs pointer at random. The randomization is not a confidential one.

**Function declaration:**

[comment]: <> (../inc/xrn_arithmetic.h)
```Xoronos_C
void xrn_initialize_rnd_mat ( 
    xmat_t * dst 
);
```

**Arguments description:**

> **output:** dst $\rightarrow$ The output of the initialization.

[comment]: <> ( docautocomplete xrn_initialize_rnd_mat )

### xrn_initialize_true_rnd_num

**Description:**

The **xrn_initialize_true_rnd_num** is used to generate a confidential random number, given as an output in xnum_t pointer location. The return value is a zero if the operation is completed successfully, negative otherwise. The random string is an optional input, which can be used to affect the result the generated randomness.

**Function declaration:**

[comment]: <> (../inc/xrn_arithmetic.h)
```Xoronos_C
int xrn_initialize_true_rnd_num ( 
    char * rnd_input, 
    xnum_t * res 
);
```

**Arguments description:**

> **input:** rnd_input $\rightarrow$ The input random bytes. \
> **output:** res $\rightarrow$ The output of the initialization.

[comment]: <> ( docautocomplete xrn_initialize_true_rnd_num )


### xrn_bin_to_hex

**Description:**

The **xrn_bin_to_hex** is used to convert a binary number to an hexadecimal one.

**Function declaration:**

[comment]: <> (../inc/xrn_arithmetic.h)
```Xoronos_C
void xrn_bin_to_hex ( 
    xnum_t xnum_in, 
    char * str_out 
);
```

**Arguments description:**

> **input:** xnum_in $\rightarrow$ The binary number representation. \
> **output:** str_out $\rightarrow$ The output hexadecimal string representation.

[comment]: <> ( docautocomplete xrn_bin_to_hex )

### xrn_hex_to_bin

**Description:**

The **xrn_hex_to_bin** is used to convert a hexadecimal number to a binary one.

**Function declaration:**

[comment]: <> (../inc/xrn_arithmetic.h)
```Xoronos_C
void xrn_hex_to_bin ( 
    char * str_in, 
    xnum_t * xnum_out  
);
```

**Arguments description:**

> **input:** str_in $\rightarrow$ The string in hexadecimal representation. \
> **output:** xnum_out $\rightarrow$ The binary number.

[comment]: <> ( docautocomplete xrn_hex_to_bin )

### xrn_bin_to_base64

**Description:**

The **xrn_bin_to_base64** is used to convert a binary number to a base64 one.

**Function declaration:**

[comment]: <> (../inc/xrn_arithmetic.h)
```Xoronos_C
void xrn_bin_to_base64 ( 
    xnum_t xnum_in, 
    char * str_out 
);
```

**Arguments description:**

> **input:** xnum_in $\rightarrow$ The binary representation. \
> **output:** str_out $\rightarrow$ The string in base64 representation.

[comment]: <> ( docautocomplete xrn_bin_to_base64 )

### xrn_base64_to_bin

**Description:**

The **xrn_base64_to_bin** is used to convert a base64 number to a binary one.

**Function declaration:**

[comment]: <> (../inc/xrn_arithmetic.h)
```Xoronos_C
int xrn_base64_to_bin ( 
    char * str_in, 
    xnum_t * xnum_out  
);
```

**Arguments description:**

> **input:** str_in $\rightarrow$ The string in base64 representation. \
> **output:** xnum_out $\rightarrow$ The binary number representation.

[comment]: <> ( docautocomplete xrn_base64_to_bin )

### Sparcity check

**Description:**

The xrn_check_sparsity function is used to check if a number has a minimum number of 1.

**Function declaration:**

[comment]: <> (../inc/xrn_arithmetic.h)
```Xoronos_C
int xrn_check_sparsity( 
    xnum_t num 
);
```

**Arguments description:**

> **input:** num $\rightarrow$ The number in binary representation. 

### End of the library

[comment]: <> (../inc/xrn_arithmetic.h)
```Xoronos_C
#endif
```

